home *** CD-ROM | disk | FTP | other *** search
/ HPAVC / HPAVC CD-ROM.iso / XLIBP202.ZIP / XLA2.DOC < prev    next >
Text File  |  1994-06-18  |  10KB  |  206 lines
  1. ╔═══════════════════════════════════════════════════════════════════════════╗
  2. ║                                                                           ║
  3. ║        XLIB v2.0 - Graphics Library for Borland/Turbo Pascal 7.0          ║
  4. ║                                                                           ║
  5. ║               Tristan Tarrant - tristant@cogs.susx.ac.uk                  ║
  6. ║                                                                           ║
  7. ╠═══════════════════════════════════════════════════════════════════════════╣
  8. ║                                                                           ║
  9. ║                                 Credits                                   ║
  10. ║                                                                           ║
  11. ║                             Themie Gouthas                                ║
  12. ║                                                                           ║
  13. ║                            Matthew MacKenzie                              ║
  14. ║                                                                           ║
  15. ║                             Tore Bastiansen                               ║
  16. ║                                                                           ║
  17. ║                                 Andy Tam                                  ║
  18. ║                                                                           ║
  19. ║                               Douglas Webb                                ║
  20. ║                                                                           ║
  21. ║                              John  Schlagel                               ║
  22. ║                                                                           ║
  23. ╠═══════════════════════════════════════════════════════════════════════════╣
  24. ║                                                                           ║
  25. ║           I informally reserve all rights to the code in XLIB             ║
  26. ║       Rights to contributed code is also assumed to be reserved by        ║
  27. ║                          the original authors.                            ║
  28. ║                                                                           ║
  29. ╚═══════════════════════════════════════════════════════════════════════════╝
  30.  
  31. ╔═══════════════════════════════════════════════════════════════════════════╗
  32. ║ DISCLAIMER                                                                ║
  33. ╚═══════════════════════════════════════════════════════════════════════════╝
  34.  
  35.   This library is distributed AS IS. The author/s specifically disclaim any
  36.   responsibility for any loss of profit or any incidental, consequential or
  37.   other damages.
  38.  
  39. ╔═══════════════════════════════════════════════════════════════════════════╗
  40. ║ XLA2 UNIT - Compression and archiving                                     ║
  41. ╚═══════════════════════════════════════════════════════════════════════════╝
  42.  
  43. The XLA2 unit implements a set of procedures and functions to handle XLA files.
  44. XLA stands for XLib Archive and is a very useful and powerful tool.
  45. Suppose you just have written a game with XLib that uses many sprites, fonts
  46. and bitmaps and you are loading all these resources from disk. This means the
  47. program's directory is cluttered with lots of files which may take up a lot
  48. of space. With XLA you can pack all of these files into one and extract them
  49. from within your program at runtime. XLA files are created with the XLARC
  50. program distributed with XLibPas2. Files inside an XLA file can be stored in
  51. two ways (for now) : uncompressed and compressed using a variation of the LZS
  52. algorithm. When extracting them, though, you don't have to worry about their
  53. format : the XLA2 routines will handle all the uncompression/unpacking for you.
  54.  
  55. The structure of an XLA file is as follows :
  56.  
  57.   Header
  58.     signature: array[0..3] of char= 'XLAS'
  59.     posdir   : longint            = The position of the archive's directory
  60.                     which is at the end of the file.
  61.     sizedir  : longint            = The number of files stored in the archive
  62.  
  63.     Files      : lots of bytes      = The files, stored sequentially
  64.            :
  65.            :
  66.            :
  67.  
  68.     Directory : array[1..sizedir] of name : array[0..11] of char= The name 
  69.           of the file
  70.     posfile  : position of the file in the archive
  71.     sizefile : the original size of the file
  72.     sizecomp : the compressed size of the file
  73.     algorithm: 0 ( No compression ) 1 ( LZS compression )
  74.  
  75. XLA2 defines the following constants :
  76.  
  77.   None = 0;    ( No compression )
  78.   LZS  = 1;    ( LZS compression )
  79.   Best = 8;    ( Best compression : not used yet )
  80.  
  81.  
  82. In order for your program to receive the extracted data or send the raw data
  83. to the XLA routines, you have to set up two procedural variables.
  84.  
  85.   XLAOutProc : procedure( var Data; size : word );
  86.   XLAInProc  : procedure( var Data; size : word; var actual : longint );
  87.  
  88. XLAOutProc will be called by the extraction routines. Data is a buffer
  89. containing the extracted data and size is the size of the buffer in bytes.
  90. The maximum size of the data buffer can be 64K, but if the extracted file is
  91. bigger than that, then XLAOutProc will be called several times and your
  92. routine should be able to handle this data.
  93. XLAInProc will be called by the encoding routines. Your routine should put
  94. size bytes of data in the Data buffer. If you can't provide the requested
  95. amount of data just put the amount of bytes you copied in actual. When there
  96. are no more bytes to compress just return a 0 in actual.
  97.  
  98. Procedures and Functions
  99.  
  100.   Function  XLZSSave( FName : string ) : boolean;
  101.   -----------------------------------------------
  102.  
  103.   Creates a standalone file with name FName. Calls XLAInProc. Returns true
  104.   if successful, false otherwise.
  105.  
  106.   Function  XLZSLoad( FName : string ) : boolean;
  107.   -----------------------------------------------
  108.  
  109.   Loads a standalone file with name FName. Calls XLAOutProc. Returns true if
  110.   successful, false otherwise.
  111.  
  112.  
  113.   function  XCreateArchive( filename : string ) : boolean;
  114.   --------------------------------------------------------
  115.  
  116.   Creates an XLA file for writing. Writes a template header to disk.
  117.   Returns true if successful.
  118.  
  119.  
  120.   function  XOpenArchive( filename : string ) : boolean;
  121.   ------------------------------------------------------
  122.  
  123.   Opens an already existing XLA file for reading. Reads in the archive's
  124.   directory. Returns true if successful.
  125.  
  126.   function  XUpdateArchive( filename : string ) : boolean;
  127.   --------------------------------------------------------
  128.  
  129.   Opens an already existing XLA file for writing/reading. Reads in the archive's
  130.   directory. Returns true if successful.
  131.  
  132.   function  XCloseArchive : boolean;
  133.   ----------------------------------
  134.  
  135.   This function has to be called when the program doesn't need to access the
  136.   XLA file any more. If the archive was opened with XCreateArchive or
  137.   XUpdateArchive the the XEndArchive function must be called instead,
  138.   otherwise the XLA file will be corrupt. Frees all the memory allocated to
  139.   the uncompression routines. Returns true if successful.
  140.  
  141.   function  XEndArchive : boolean;
  142.   --------------------------------
  143.  
  144.   This function has to be called when the program has finished creating or
  145.   updating an archive. It writes the archive's directory at the end of the
  146.   file and updates the header to reflect any changes. Frees all memory
  147.   allocated to the compression routines. Returns true if successful.
  148.  
  149.   function  XLAGet( fname : string ) : boolean;
  150.   ---------------------------------------------
  151.  
  152.   Extracts a file from the currently open archive. Calls XLAOutProc.
  153.   Returns true if successful.
  154.  
  155.   function  XLAPut( fname : string; mode : word ) : boolean;
  156.   ----------------------------------------------------------
  157.  
  158.   Adds a file to the currently open archive. Calls XLAInProc. Returns true
  159.   if successful. Mode can be either None or LZS.
  160.  
  161.   procedure XPrintDir;
  162.   --------------------
  163.  
  164.   Displays a formatted list of all the files contained in the archive.
  165.  
  166.  
  167.   function  XLAGetFileInfo( fname : string; var origsize, compsize : longint;
  168.                 mode : word ) : boolean;
  169.   ---------------------------------------------------------------------------
  170.  
  171.   Collects information about a particular file in the archive. Origsize
  172.   contains the length of the uncompressed file. Compsize contains the size of
  173.   the compressed file. Mode contains the algorithm used to store the file.
  174.   Returns true if successful.
  175.  
  176.  
  177.   function  XLAFindFirst( pattern : string; var match : string ) : boolean;
  178.   -------------------------------------------------------------------------
  179.  
  180.   Searches through the archive's directory for the first file matching pattern.
  181.   and returns it in match. pattern can contain * wildcards in the standard DOS
  182.   notation. It doesn't support ? wildcards. Returns true if successful.
  183.  
  184.   function  XLAFindNext( var match : string ) : boolean;
  185.   ------------------------------------------------------
  186.  
  187.   Finds the next file matching the pattern given in a previous call to
  188.   XLAFindFirst and returns it in match. Returns true if successful.
  189.  
  190.   To better understand how these procedures/functions are used, examine the
  191.   source for xlarc.
  192.  
  193. WARNING!!!
  194.   The XLA utilities don't allow you to update files that are already inside
  195. an archive, because this would require the creation of a temporary file.
  196.  
  197. Notes:
  198.  
  199.   If you know anything about the WAD file structure for iD's DOOM then you 
  200. should already have a rough idea of how this unit handles things. The major 
  201. difference between XLAs and WADs is that the former can be compressed while the 
  202. latter can't. WADs, though, have one notable feature : they can be patched with 
  203. newer versions of the files in the archive. If there is a demand for this kind
  204. of thing I will include it in the next release.
  205.  
  206.